home *** CD-ROM | disk | FTP | other *** search
/ Workbench Add-On / Workbench Add-On - Volume 1.iso / BBS-Archive / DiskUtil / Misc / BTNTape.lha / doc / features.doc < prev    next >
Text File  |  1994-04-03  |  11KB  |  245 lines
  1. This section of the BTN documentation discusses the features of BTN
  2. that are useful, interesting, or different from most tape software.
  3.  
  4. ****    BTNtape:  an AmigaDOS handler for SCSI tape drives
  5. ****       Version 3.0   3/14/94
  6. ****       Freeware by Bob Rethemeyer   (drBob@cup.portal.com)
  7. ****    (c) Copyright 1990, 1994  Robert Rethemeyer.
  8.  
  9.  
  10. CONTENTS:
  11.      The Monitor program
  12.      End-of-tape handling
  13.      Error handling
  14.      Read-only mode
  15.      Append-only mode
  16.      File number tracking
  17.      Raw command interface
  18.      User-specified mode select
  19.      BUGS (anomalous features)
  20.  
  21.  
  22. THE MONITOR PROGRAM
  23.  
  24.      Included in with the handler is the TAPEMON program.  TAPEMON is
  25.      a program that runs under a separate CLI and prints one-liner
  26.      messages from the handler.  The messages include the current
  27.      tape operation and block number, and error and sense codes.
  28.      The handler will run with or without TAPEMON; i.e. TAPEMON is optional.
  29.      TAPEMON may be started either before or after the handler is mounted.
  30.      Read tapemon.doc for more information.
  31.  
  32.  
  33. END-OF-TAPE HANDLING
  34.  
  35.   NOTE: I cannot fully guarantee BTN's handling of end-of-tape conditions,
  36.   because I was unable to test it.  If you want to risk it anyway,
  37.   keep these things in mind:
  38.  
  39.      If the application reaches the end of the tape, the handler will put up
  40.      a requester asking you to insert the next tape and click "Continue",
  41.      or click "Abort".  The continue option allows the application program
  42.      to access a file across multiple tape volumes without interruption.
  43.      WAIT FOR TAPE MOTION TO STOP on the new tape before clicking Continue.
  44.      If you click Abort, end-of-file is returned to the application,
  45.      and any unused data in the buffers is discarded.
  46.  
  47.    *IMPORTANT NOTES*
  48.  
  49.      *  EOT handling may not work correctly on all drives.  Test it before
  50.      trusting your data to it.  Read the archive back using the -t option
  51.      of TAR.  If TAR hiccups on a file after the tape swap, it doesn't work.
  52.      You can backup partitions or directories smaller than the tape capacity
  53.      to avoid this situation.
  54.  
  55.      *  EOT handling for direct access drives will work only if the drive
  56.      supports the READ_CAPACITY SCSI command.  If you see no "Capacity"
  57.      message from TAPEMON, then EOT handling is unavailable.
  58.  
  59.  
  60. ERROR HANDLING
  61.  
  62.      This tape handler deals with tape errors in only a rudimentary way.
  63.      If the tape drive cannot deal with a medium or device error, it
  64.      reports it to BTN as bad status.  BTN, in turn, can pass bad status
  65.      to your application program, depending on the ER flag (see install.doc)
  66.      and a requester choice.  If the ER flag is 0, your application
  67.      receives status -1 for Read() or Write().   If the ER flag is 1,
  68.      you will be shown a requester giving you a choice of how you want
  69.      to deal with the error: IGNORE or FAIL.  If you click IGNORE,
  70.      BTN returns good status to your application even though the data
  71.      associated with the error may be lost or corrupted.  This allows
  72.      the application to continue processing the remaining data.
  73.      Clicking FAIL will return -1 as described above.
  74.  
  75.  
  76. READ-ONLY MODE
  77.  
  78.      If you want to reduce the possibility that someone can write on
  79.      a tape with valuable data on it, even if the cartridge is not
  80.      write-protected, you can force BTN to operate in read-only mode.
  81.      Do this by setting the RO startup flag to 1 (see install.doc).
  82.      When operating in this mode, BTN will return error status whenever
  83.      an attempt is made to open the file for writing.  However, it
  84.      does not protect the tape from damage by raw commands.
  85.  
  86.  
  87. APPEND-ONLY MODE
  88.  
  89.      If you have tapes with existing files, and you usually wish to just
  90.      append new files onto them, you can reduce the risk of accidentally
  91.      destroying the existing files by operating BTN in "append-only" mode.
  92.      Use the AO flag in the startup string (see install.doc).
  93.      When operating in this mode, BTN rejects attempts to open the tape
  94.      for writing unless:
  95.            a) the access name is TAPE:APP or TAPE:END
  96.            b) the access name is TAPE:NR and the tape is already
  97.                positioned after the last-written file
  98.  
  99.  
  100. FILE NUMBER TRACKING
  101.  
  102.      You can place multiple files on a tape, with each file separated
  103.      by a filemark.  If you have many files on a tape, keeping track
  104.      of them becomes unwieldy.  BTN provides a way for user programs
  105.      to ask it for the file number of the file at the current position.
  106.      For example, you could write an ARexx script to update a "directory"
  107.      file on the hard disk which lists the date and file number of
  108.      each archive on the tape.  Later you can use the number to
  109.      read the file using the TAPE:n access mode (n=file number).
  110.  
  111.      The file number is a value maintained by BTN; it is not obtained
  112.      from the tape drive.  BTN basically just counts filemarks.
  113.      When the tape is inserted or rewound, the number is reset to zero.
  114.      For reading and writing, the number gets incremented when the
  115.      file is closed.  If you append a file on the tape, BTN will count
  116.      each file until it reaches the append location.
  117.  
  118.      However, to append a file and keep the file number accurate, you
  119.      must not use TAPE:APP.  Instead you must use "TAPE:END", which
  120.      performs the same function as TAPE:APP, but counts each file until
  121.      it reaches the end.  Unfortunately, TAPE:END is slower than TAPE:APP.
  122.      Also note, using some raw commands may fool the counter.
  123.  
  124.      The file number is displayed in the TAPEMON "Opened" and "Closed"
  125.      messages, or may be obtained from the handler by a program.
  126.      To obtain the current file number, open, read, and close TAPE:POS .
  127.      (You can do this manually using the CLI command  "TYPE TAPE:POS".)
  128.  
  129.      This pseudo file does not access the tape, it just returns a
  130.      short string containing the file number in decimal. 0 is the
  131.      first file on the tape, 1 is the second, etc.  If BTN isn't sure
  132.      of the number, it returns -1.  Rewinding the tape will reset it.
  133.      You should read the number BEFORE opening the associated file,
  134.      or subtract 1 from the number obtained AFTER closing the file.
  135.      You cannot read the number while the tape is active; it must be idle.
  136.  
  137.      If you are using a direct access (3M) drive, the file number returned
  138.      is actually the block number (direct access drives don't have filemarks).
  139.      Also read and save the block number AFTER writing a file to know where
  140.      to write the next file.
  141.  
  142.  
  143. RAW COMMAND INTERFACE
  144.  
  145.      This handler provides a means to send your own SCSI control commands
  146.      to the tape drive, without the need for a special program.
  147.      Some control commands you might want to send it would be REWIND,
  148.      UNLOAD, ERASE, FORMAT, LOCK, etc.  Only control commands may be sent-
  149.      there is no provision for any data transfer; don't try it.
  150.      (As you might guess, raw commands can be dangerous.)
  151.  
  152.      The raw command mode is invoked by writing data to the file name
  153.      "TAPE:RAWCMD". This magic word is how the handler knows you
  154.      want to do a raw command.
  155.  
  156.      You send a command via RAWCMD using the CLI "ECHO" command:
  157.             ECHO >TAPE:RAWCMD "hex command bytes..."
  158.  
  159.      You can put the ECHO command in a script or make a shell alias with it.
  160.      The exact value of the data bytes is determined by the byte format of
  161.      the SCSI command you want to send. (Refer to your drive documentation.)
  162.      The data must contain only hex digits and spaces, terminated by a newline.
  163.      Each byte of the raw command should be specified as a pair of hex
  164.      digits;  separate bytes by spaces.  Up to 12 bytes may be specified.
  165.      Trailing omitted bytes are assumed to be zeroes.
  166.  
  167.      Command examples:
  168.         Rewind:     "01"
  169.         Erase:      "19"  (sequential drives only)
  170.         Retension:  "1B 00 00 00 03"
  171.  
  172.      I have included in the distribution a small ARexx script named
  173.      TAPE.REXX .  It will issue some of the common control commands
  174.      for you.  Refer to the script for more information.
  175.  
  176.  
  177. USER-SPECIFIED MODE SELECT
  178.  
  179.      In recognition of the fact that it will never be able to provide
  180.      switches for all possible modes of all tape drives, BTNtape
  181.      allows you to set the modes of the drive directly.
  182.      These modes might include:  buffering, speed, auto-loading,
  183.      disconnect/reconnect, medium type, etc.
  184.  
  185.    *NOTE* Do not use this feature unless you know what you are doing.
  186.      This feature is provided for the convenience of "power users".
  187.      Most drives can get by with defaults if you do not set the modes,
  188.      so it is unlikely that not setting a mode will cause problems.
  189.  
  190.      Drive modes are set using the SCSI command MODE_SELECT (0x15).
  191.      BTNtape will send its own MODE_SELECT to the drive if necessary
  192.      to set the drive to fixed block mode and set the block length.
  193.      But you may also send this command to the drive at other times,
  194.      using any data you wish.
  195.  
  196.      The command is sent in a manner very similar to the RAWCMD
  197.      method described above, but the magic word MODESEL is
  198.      used instead.  The handler provides the SCSI command,
  199.      and you provide the data.  The data is specified in an ECHO
  200.      command as pairs of hex digits separated by spaces:
  201.             ECHO >TAPE:MODESEL "hex data bytes..."
  202.  
  203.      Since each drive has different things that are affected by MODE_SELECT,
  204.      you MUST refer to the programming documentation for your drive.
  205.      But in general, the mode select data consists of a parameter
  206.      list, a block descriptor, and vendor unique parameters.
  207.     *NOTE*  If you specify a block descriptor, it will behoove you to
  208.      specify the same block length as found in the mountlist entry
  209.      when using fixed block mode, or zero if using variable block mode.
  210.  
  211.      The handler counts the number of bytes you enter (up to 64),
  212.      and uses that for the SCSI command data length.  The drive may
  213.      be fussy about the length, so enter exactly the number of bytes
  214.      as described in your docs.
  215.  
  216.      Mode Select data example:
  217.  
  218.        --parmlist-   ----block-descriptor---   vendorparms
  219.        00 10 00 08   03 00 00 00 00 00 04 00   11 22 33 44
  220.           |     |    |                 || ||
  221.   Buff_mode  BD_Len  Density         Blk_Len
  222.  
  223.  
  224.  
  225. BUGS
  226.  
  227.      Avoid using the INFO command from another CLI while a tape operation
  228.      is in progress.  It may cause BTN to crash the machine.  This may
  229.      also happen with any program that causes a packet to be sent to BTN.
  230.  
  231.      The variable block mode of operation (VB-1) is not allowed in this
  232.      version;  it has never really worked right.
  233.  
  234.      Writing tapes across more than one tape cartridge is not recommended on
  235.      sequential drives. Try not to hit the end of the tape.  Although BTN
  236.      is designed to handle this situation, I have not been able to test it.
  237.  
  238.      If you use the old Xoper or ARTM utilities, and display the device list,
  239.      the entry for TAPE: will show garbage, and/or the Amiga may crash.
  240.      I believe this to be a bug in those programs, but this will be little
  241.      consolation to you after your machine crashes.
  242.  
  243.      The TAPE: device cannot be gotten rid of without rebooting.
  244.  
  245.